Related issues

• Follow-up: STU-1956

How AI was used in this PR

This PR is AI-assisted and intentionally large. AI was used to draft the initial agentic UI onboarding implementation, iterate on UI states, identify duplicated/default UI behavior, and review cross-app risk. The implementation has been manually reviewed and adjusted, especially around shared sync behavior, default UI impact, and WordPress.com site filtering.

Because of the PR size, reviewers should not treat the raw diff as the primary review artifact. Please use the review guide below to focus on the product and architecture decisions this code implies.

Executive summary

This PR adds an Add Site onboarding flow to the agentic UI (apps/ui, ui-classic) so users can build a new site, start from a blueprint, import a backup, or connect a WordPress.com/Pressable site. The main intent is to bring the core Add Site flows into the agentic UI while the default Studio UI still exists.

Some shared helpers were moved into tools/common so the default UI and agentic UI display the same blueprint curation, site thumbnails, and environment labels. The connect flow creates a local site shell, persists the WordPress.com connection, and starts a first pull from the live site. That lifecycle is intentionally not fully solved in this PR; durable first-pull lifecycle/error state is tracked separately in STU-1956.

The most important review is not line-by-line CSS. Please focus on whether the flow boundaries, shared sync/API changes, and agentic-vs-default UI architecture are acceptable.

Proposed Changes

• Adds an agentic UI Add Site entry point with Build a new site, Connect a site, and Import from backup paths.
• Updates the build/new-site path with an empty-site option, featured blueprints, blueprint upload/deep-link handoff, and the shared create-site form.
• Updates import so a backup can be dropped or selected from the onboarding home, then configured in the create-site form.
• Adds a WordPress.com/Pressable connect flow that groups remote sites by syncability, creates a local site shell, persists the connection, and starts the initial pull.
• Moves common blueprint, sync environment, and mshots helpers into tools/common so the default UI and agentic UI do not drift.
• Updates shared sync site fetching to use the paginated /me/sites v1.3 API and the documented filters param.

Review guide

Please focus review here

1. Overall Add Site flow shape

   • Entry point: apps/ui/src/ui-classic/router/route-onboarding-home/index.tsx
   • Routes: create, blueprint, import, connect
   • Question: are these the right user-facing choices and navigation paths for the agentic UI?

2. Connect remote site architecture

   • apps/ui/src/ui-classic/router/route-onboarding-connect/index.tsx
   • apps/ui/src/data/queries/use-wpcom-sites.ts
   • apps/studio/src/modules/sync/lib/ipc-handlers.ts
   • Question: is creating a local shell, persisting the connection, then starting pull the right boundary for this PR?

3. Shared sync/API behavior

   • tools/common/lib/sync/sync-api.ts
   • tools/common/lib/sync/transform-sites.ts
   • apps/studio/src/stores/sync/wpcom-sites.ts
   • apps/cli/lib/api.ts
   • Question: are the /me/sites v1.3 pagination, filters=atomic,wpcom, staging/environment handling, and CLI/default UI impacts acceptable?

4. Shared helpers extracted from default UI

   • tools/common/lib/blueprint-curation.ts
   • tools/common/lib/sync/environment-utils.ts
   • tools/common/lib/sync/mshots.ts
   • Question: are these reasonable shared boundaries, or should any remain UI-local?

5. State handoff patterns

   • apps/ui/src/lib/pending-slot.ts
   • apps/ui/src/lib/pending-backup.ts
   • apps/ui/src/lib/pending-blueprint.ts
   • apps/ui/src/hooks/use-add-site-listener.ts
   • Question: is this acceptable as a lightweight route handoff mechanism for files/deep links?

Okay to skim

• Most CSS modules and visual layout polish.
• SVG onboarding illustrations.
• Dot-grid animation implementation, unless you are specifically reviewing performance/visual polish.
• Mechanical connector type additions that expose existing IPC capabilities to apps/ui.

Diff breakdown

• New agentic UI onboarding UX: home picker, create/blueprint/import/connect routes, footer actions, busy overlay, focus handling, keyboard navigation.
• Remote site connection: paginated WordPress.com site picker, syncability grouping, screenshots, environment badges, connection persistence, first-pull trigger.
• Shared behavior: blueprint curation, mshots, environment labels, syncable site fetching.
• Default UI / CLI impact: shared /me/sites fetch now affects CLI sync site resolution; default UI staging/environment handling was aligned.
• Tests: focused tests for dot grid, add-site listener, and paginated WP.com site query hook.

Screenshots

Known tradeoffs / follow-ups

• The agentic UI still lacks a durable lifecycle state system for the first pull after connecting a site. Today it starts the pull after connection and relies on existing sync activity. STU-1956 tracks a proper lifecycle/error model.
• This PR duplicates some default UI Add Site behavior intentionally. The expectation is that the default UI eventually goes away, so perfect abstraction is not the goal here.
• The /me/sites fetch now uses v1.3 pagination. This should improve large-account behavior, but it is shared with CLI/default UI and deserves review.

Safety checklist

• Feature scope: primarily agentic UI; shared sync helpers affect default UI and CLI.
• Migrations: none.
• Storage changes: no config schema migration.
• API compatibility: /me/sites moved to v1.3 for shared syncable-site fetching; uses documented filters param.
• Rollback: revert this PR to remove agentic Add Site onboarding; no persisted migration to unwind.
• Performance: dot grid honors reduced motion and sleeps when inactive; remote site picker uses paginated fetch/search.
• Security: no new credentials stored; WordPress.com auth continues through existing OAuth/IPC paths.
• Manual testing needed: create empty site, create from blueprint, upload blueprint, import backup, connect WP.com/Pressable site, verify default UI sync picker still behaves correctly.

Testing Instructions

Automated checks used during this PR:

• npx eslint --fix on modified TypeScript/TSX files
• npm run typecheck
• npm test -- apps/ui/src/data/queries/use-wpcom-sites.test.tsx apps/ui/src/hooks/use-add-site-listener.test.tsx
• npm -w @studio/ui run dev:web -- --host 127.0.0.1 --port 5300, then browser smoke checks for /onboarding, /onboarding/blueprint, /onboarding/create, and /onboarding/connect in light and dark color schemes. The standalone web target renders these routes; its expected backend-connection failures were filtered out of the console check.

Suggested reviewer checks:

• Start the app with Agentic UI enabled and open Add site.
• Confirm the home screen shows the dot-grid background, three illustrated cards, and centered header copy.
• Exercise Build a new site, both empty-site and blueprint paths, and confirm footer Back behavior.
• Drop or choose a supported backup from the home card and confirm the import configure step seeds a sensible name.
• Sign in and open Connect a site; confirm syncable sites are visible, grouped sections make sense, search behaves correctly, and single-site/grouped-card sizing feels natural.
• Smoke-test the default UI sync picker and CLI site lookup paths because shared /me/sites behavior changed.
• Check both light and dark mode in Electron.

Pre-merge Checklist

• CI passes.
• TypeScript check passes.
• Relevant tests pass.
• Human visual review in Electron with an authenticated WordPress.com account.
• Reviewer has explicitly looked at the shared sync/API changes.
• Reviewer accepts the first-pull lifecycle follow-up being handled outside this PR.
• Have you checked for TypeScript, React or other console errors?